Mail Source Specifiers

Next: Mail Source Customization, Up: Mail Sources

6.4.4.1 Mail Source Specifiers

You tell Gnus how to fetch mail by setting mail-sources (see Fetching Mail) to a mail source specifier.

Here's an example:

     (pop :server "pop3.mailserver.com" :user "myname")

As can be observed, a mail source specifier is a list where the first element is a mail source type, followed by an arbitrary number of keywords. Keywords that are not explicitly specified are given default values.

The mail-sources is global for all mail groups. You can specify an additional mail source for a particular group by including the group mail specifier in mail-sources, and setting a mail-source group parameter (see Group Parameters) specifying a single mail source. When this is used, mail-sources is typically just (group); the mail-source parameter for a group might look like this:

     (mail-source . (file :path "home/user/spools/foo.spool"))

This means that the group's (and only this group's) messages will be fetched from the spool file ‘/user/spools/foo.spool’.

The following mail source types are available:

file

Get mail from a single file; typically from the mail spool.

Keywords:

:path: The file name. Defaults to the value of the MAIL environment variable or the value of rmail-spool-directory (usually something like /usr/mail/spool/user-name).
:prescript
:postscript: Script run before/after fetching mail.

An example file mail source:

          (file :path "/usr/spool/mail/user-name")

Or using the default file name:

          (file)

If the mail spool file is not located on the local machine, it's best to use POP or IMAP or the like to fetch the mail. You can not use ange-ftp file names here—it has no way to lock the mail spool while moving the mail.

If it's impossible to set up a proper server, you can use ssh instead.

          (setq mail-sources
                '((file :prescript "ssh host bin/getmail >%t")))

The ‘getmail’ script would look something like the following:

          #!/bin/sh
          #  getmail - move mail from spool to stdout
          #  flu@iki.fi

          MOVEMAIL=/usr/lib/emacs/20.3/i386-redhat-linux/movemail
          TMP=$HOME/Mail/tmp
          rm -f $TMP; $MOVEMAIL $MAIL $TMP >/dev/null && cat $TMP

Alter this script to fit the ‘movemail’ and temporary file you want to use.

directory

Get mail from several files in a directory. This is typically used when you have procmail split the incoming mail into several files. That is, there is a one-to-one correspondence between files in that directory and groups, so that mail from the file foo.bar.spool will be put in the group foo.bar. (You can change the suffix to be used instead of .spool.) Setting nnmail-scan-directory-mail-source-once to non-nil forces Gnus to scan the mail source only once. This is particularly useful if you want to scan mail groups at a specified level.

There is also the variable nnmail-resplit-incoming, if you set that to a non-nil value, then the normal splitting process is applied to all the files from the directory, Splitting Mail.

Keywords:

:path: The name of the directory where the files are. There is no default value.
:suffix: Only files ending with this suffix are used. The default is ‘.spool’.
:predicate: Only files that have this predicate return non-nil are returned. The default is identity. This is used as an additional filter—only files that have the right suffix and satisfy this predicate are considered.
:prescript
:postscript: Script run before/after fetching mail.

An example directory mail source:

          (directory :path "/home/user-name/procmail-dir/"
                     :suffix ".prcml")

pop

Get mail from a POP server.

Keywords:

:server

The name of the POP server. The default is taken from the MAILHOST environment variable.

:port

The port number of the POP server. This can be a number (eg, ‘:port 1234’) or a string (eg, ‘:port "pop3"’). If it is a string, it should be a service name as listed in /etc/services on Unix systems. The default is ‘"pop3"’. On some systems you might need to specify it as ‘"pop-3"’ instead.

:user

The user name to give to the POP server. The default is the login name.

:password

The password to give to the POP server. If not specified, the user is prompted.

:program

The program to use to fetch mail from the POP server. This should be a format-like string. Here's an example:

               fetchmail %u@%s -P %p %t

The valid format specifier characters are:

‘t’: The name of the file the mail is to be moved to. This must always be included in this string.
‘s’: The name of the server.
‘P’: The port number of the server.
‘u’: The user name to use.
‘p’: The password to use.

The values used for these specs are taken from the values you give the corresponding keywords.

:prescript

A script to be run before fetching the mail. The syntax is the same as the :program keyword. This can also be a function to be run.

:postscript

A script to be run after fetching the mail. The syntax is the same as the :program keyword. This can also be a function to be run.

:function

The function to use to fetch mail from the POP server. The function is called with one parameter—the name of the file where the mail should be moved to.

:authentication

This can be either the symbol password or the symbol apop and says what authentication scheme to use. The default is password.

If the :program and :function keywords aren't specified, pop3-movemail will be used. If pop3-leave-mail-on-server is non-nil the mail is to be left on the POP server after fetching when using pop3-movemail. Note that POP servers maintain no state information between sessions, so what the client believes is there and what is actually there may not match up. If they do not, then you may get duplicate mails or the whole thing can fall apart and leave you with a corrupt mailbox.

Here are some examples for getting mail from a POP server. Fetch from the default POP server, using the default user name, and default fetcher:

          (pop)

Fetch from a named server with a named user and password:

          (pop :server "my.pop.server"
               :user "user-name" :password "secret")

Use ‘movemail’ to move the mail:

          (pop :program "movemail po:%u %t %p")

maildir

Get mail from a maildir. This is a type of mailbox that is supported by at least qmail and postfix, where each file in a special directory contains exactly one mail.

Keywords:

:path: The name of the directory where the mails are stored. The default is taken from the MAILDIR environment variable or ~/Maildir/.
:subdirs: The subdirectories of the Maildir. The default is ‘("new" "cur")’.
You can also get mails from remote hosts (because maildirs don't suffer from locking problems).

Two example maildir mail sources:

          (maildir :path "/home/user-name/Maildir/"
                   :subdirs ("cur" "new"))

          (maildir :path "/user@remotehost.org:~/Maildir/"
                   :subdirs ("new"))

imap

Get mail from a IMAP server. If you don't want to use IMAP as intended, as a network mail reading protocol (ie with nnimap), for some reason or other, Gnus let you treat it similar to a POP server and fetches articles from a given IMAP mailbox. See Using IMAP, for more information.

Keywords:

:server

The name of the IMAP server. The default is taken from the MAILHOST environment variable.

:port

The port number of the IMAP server. The default is ‘143’, or ‘993’ for TLS/SSL connections.

:user

The user name to give to the IMAP server. The default is the login name.

:password

The password to give to the IMAP server. If not specified, the user is prompted.

:stream

What stream to use for connecting to the server, this is one of the symbols in imap-stream-alist. Right now, this means ‘gssapi’, ‘kerberos4’, ‘starttls’, ‘tls’, ‘ssl’, ‘shell’ or the default ‘network’.

:authentication

Which authenticator to use for authenticating to the server, this is one of the symbols in imap-authenticator-alist. Right now, this means ‘gssapi’, ‘kerberos4’, ‘digest-md5’, ‘cram-md5’, ‘anonymous’ or the default ‘login’.

:program

When using the `shell' :stream, the contents of this variable is mapped into the imap-shell-program variable. This should be a format-like string (or list of strings). Here's an example:

               ssh %s imapd

Make sure nothing is interfering with the output of the program, e.g., don't forget to redirect the error output to the void. The valid format specifier characters are:

‘s’: The name of the server.
‘l’: User name from imap-default-user.
‘p’: The port number of the server.

The values used for these specs are taken from the values you give the corresponding keywords.

:mailbox

The name of the mailbox to get mail from. The default is ‘INBOX’ which normally is the mailbox which receives incoming mail.

:predicate

The predicate used to find articles to fetch. The default, ‘UNSEEN UNDELETED’, is probably the best choice for most people, but if you sometimes peek in your mailbox with a IMAP client and mark some articles as read (or; SEEN) you might want to set this to ‘1:*’. Then all articles in the mailbox is fetched, no matter what. For a complete list of predicates, see RFC 2060 section 6.4.4.

:fetchflag

How to flag fetched articles on the server, the default ‘\Deleted’ will mark them as deleted, an alternative would be ‘\Seen’ which would simply mark them as read. These are the two most likely choices, but more flags are defined in RFC 2060 section 2.3.2.

:dontexpunge

If non-nil, don't remove all articles marked as deleted in the mailbox after finishing the fetch.

An example IMAP mail source:

          (imap :server "mail.mycorp.com"
                :stream kerberos4
                :fetchflag "\\Seen")

group

Get the actual mail source from the mail-source group parameter, See Group Parameters.

Common Keywords

Common keywords can be used in any type of mail source.

Keywords:

:plugged

If non-nil, fetch the mail even when Gnus is unplugged. If you use directory source to get mail, you can specify it as in this example:

               (setq mail-sources
                     '((directory :path "/home/pavel/.Spool/"
                                  :suffix ""
                                  :plugged t)))

Gnus will then fetch your mail even when you are unplugged. This is useful when you use local mail and news.

6.4.4.2 Function Interface

Some of the above keywords specify a Lisp function to be executed. For each keyword :foo, the Lisp variable foo is bound to the value of the keyword while the function is executing. For example, consider the following mail-source setting:

     (setq mail-sources '((pop :user "jrl"
                               :server "pophost" :function fetchfunc)))

While the function fetchfunc is executing, the symbol user is bound to "jrl", and the symbol server is bound to "pophost". The symbols port, password, program, prescript, postscript, function, and authentication are also bound (to their default values).

See above for a list of keywords for each type of mail source.